ATSUFindFontFromName

OSStatus ATSUFindFontFromName (
                     Ptr iName,
                     ByteCount iNameLength,
                     FontNameCode iFontNameCode,
                     FontPlatformCode iFontNamePlatform,
                     FontScriptCode iFontNameScript,
                     FontLanguageCode iFontNameLanguage,
                     ATSUFontID *oFontID);

iName

A pointer to a buffer. Pass the name string of the font you want to obtain.

iNameLength

The length (in bytes) of the font name string.

iFontNameCode

A value of type FontNameCode. Pass the type of the font name string. See Font Name Code Constants for a description of possible values.

iFontNamePlatform

A value of type FontPlatformCode. Pass the encoding of the font name string. See Font Name Platform Constants for a description of possible values. You can pass the kFontNoPlatform constant if you do not care about the encoding. In this case, ATSUFindFontFromName will pass back the first font in the name table matching the other font name parameters.

iFontNameScript

A value of type FontScriptCode. Pass the script ID of the font name string. Depending upon the font name platform, see Macintosh Platform Script Code Constants, Microsoft Platform Script Code Constants, or Unicode Platform Script Code Constants for a description of possible values. You can pass the kFontNoScript constant if you do not care about the script ID. In this case, ATSUFindFontFromName will pass back the first font in the name table matching the other font name parameters.

iFontNameLanguage

A value of type FontLanguageCode. Pass the language of the font name string. See Font Name Language Constants for a description of possible values. You can pass the kFontNoLanguage constant if you do not care about the language. In this case, ATSUFindFontFromName will pass back the first font in the name table matching the other font name parameters.

oFontID

A pointer to a value of type ATSUFontID. On return, the first font that matches the specified name code, platform, script, and language. If no installed font matches these parameters, ATSUFindFontFromName passes back the constant kATSUInvalidFontID and returns the result code kATSUInvalidFontErr.

function result

A result code. See Result Codes.

DISCUSSION

Because ATSUI cannot guarantee the uniqueness of names among installed fonts, the ATSUFindFontFromName function finds the first (but not necessarily the only) font that matches the specified name, platform, language, and script. If you want to find, for an indexed font name, the font name and information about the name like type, platform, script ID, and language, call the function ATSUGetIndFontName. If you want to find the ID of the first font in a font name table with a particular font name code, language, platform, and script, call the function ATSUFindFontName.

ATSUFindFontFromName is provided for convenience only. You may wish to replicate its functionality if you wish create a more sophisticated name-matching algorithm or better guarantee the uniqueness of names among installed fonts.

SPECIAL CONSIDERATIONS

ATSUFindFontFromName may allocate memory in your application heap, unless you designate a different heap by calling the function ATSUCreateMemorySetting.

VERSION NOTES

Available beginning with ATSUI 1.0.